Codex review: needs real behavior proof before merge. Reviewed August 4, 2026, 5:07 PM ET / 21:07 UTC.

ClawSweeper review

What this changes

This PR adds 474 lines of non-shipping design tokens, static component examples, and design guidance under .agents/design/ for the Windows Hub tray app.

Merge readiness

⛔ Blocked until stronger real behavior proof is added - 14 items remain

Keep open. Current main does not contain this catalog, but the proposed agent-facing authority conflicts with the current Reactor-owned chat contract and lacks current-head validation and proof.

Priority: P2
Reviewed head: d03a4ffcda603e12fc6a75bfadf731dec6e21b55
Owner decision: Required. See Decision needed.

Review scores

Verification

How this fits together

Windows Hub is a native WinUI tray application whose chat surface is now rendered by Reactor components using Fluent theme resources. The new catalog would guide designers and coding agents before they port a design into those shipping surfaces.

flowchart LR
  A[Native chat and WinUI code] --> B[Fluent resources and behavior]
  B --> C[Design catalog]
  C --> D[Agent and designer guidance]
  D --> E[Reactor and WinUI implementation]
  E --> F[Windows Hub users]

Decision needed

Why: The PR adds a new contributor and agent authority surface rather than repairing existing runtime behavior; the repository must choose whether to support and maintain that surface.

Before merge

• Add real behavior proof - Needs stronger real behavior proof before merge: The PR contains screenshots, but they predate the current components.jsonc migration; add redacted current-head parse/reference output and Light, Dark, and High Contrast gallery proof before merge. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
• Make native UI behavior canonical (P1) - The catalog calls itself the source of truth for design, but current production chat is Reactor-owned and uses native Fluent resources. Make the catalog explicitly derived from native behavior and resource mappings so future agents cannot treat it as a parallel authority.
• Mark static chat patterns as partial references (P2) - The catalog presents chat patterns as shipping guidance, while the current Reactor root also owns attachments, queued-send cancellation, tool-call visibility, voice state, settings, and stop/read-aloud behavior. Link the canonical owners and state the omitted contract instead of implying full parity.
• Update the retired JSX catalog reference (P2) - This PR introduces components.jsonc, but current composer documentation still points agents to .agents/design/components.jsx. Update that reference in the same PR so the repository does not document a catalog file that is absent after merge.
• Remove em dashes from agent-facing guidance (P2) - The added catalog instructions use em dashes. Repository policy prohibits em dashes in agent-facing help, so replace them with commas, colons, or hyphens throughout the added design files.
• Add repository-owned catalog validation (P2) - The new JSONC catalog is not part of the build or test graph, so a schema or component-reference break in the external canvas format can merge unnoticed. Add a focused repository-owned parse/reference smoke check before using this as shared guidance.
• Resolve merge risk (P1) - If agents treat the catalog as the authoritative design source, its static values and incomplete chat patterns can drift from the shipping Reactor behavior, Fluent resource mappings, and accessibility states.
• Resolve merge risk (P1) - The new JSONC catalog depends on an external canvas schema but has no repository-owned parse, reference, or rendering smoke check.
• Resolve merge risk (P1) - Complete local PR-head object inspection was blocked by an unreachable promisor remote; no claim is made that the entire head tree was locally read.
• Complete next step (P2) - A maintainer must first sponsor the repository-owned catalog boundary, and the contributor must supply current-head proof that automation cannot create on their behalf.
• Improve patch quality - Make the catalog explicitly derived and partial, then repair the JSX reference and agent-facing copy.
• Improve patch quality - Add a repository-owned JSONC parse/reference smoke check.
• Improve patch quality - Post redacted current-head Light, Dark, and High Contrast catalog proof in the PR body.

Findings

• [P1] Make native UI behavior canonical — .agents/design/design.json:6
• [P2] Mark static chat patterns as partial references — .agents/design/components.jsonc:13-17
• [P2] Update the retired JSX catalog reference — .agents/design/components.jsonc:1

🤖 Copilot assistant note, posted on Scott's behalf — this is not Scott writing personally.

I was initially confused about the intended authority boundary here. I inferred that the JSX was a non-shipping visual reference derived from the native WinUI app, but the current wording sends mixed signals:

• design.json says the tokens were derived from the repository's native XAML/C# surfaces.
• principles.md calls this “the design system” and says designers write here while developers and Copilot read it.
• The PR description calls .agents/design/ a “source of truth.”

Because this is a native WinUI application, I suggest making the boundary explicit for future agents and contributors:

Native WinUI XAML/C# and observed product behavior are canonical. The JSX and design files are non-shipping, derived visual examples for Colophon and Copilot. When they differ, native wins.

It would also help to qualify or remove “source of truth,” and name who is responsible for synchronizing these derived examples after native UI changes. That clarity would have prevented my initial misreading and should keep future bots from treating the JSX as a parallel product authority.

Pushed an update that reworks the authority framing in response to @scott's note about .agents/design/ being described as "the source of truth".

The seed now uses Colophon's new port-target model instead of a flat source-of-truth claim:

• The design files stay the source of truth for design (tokens, component intent, principles) and are framework-agnostic. components.jsx is design intent for the canvas preview — explicitly not shipping code.
• How a design ships is now recorded per-surface in design.json under authority:
  • Default: ships as Native WinUI 3 / C#, ported via win-dev-skills.
  • Chat surface (ChatBubble, ChatComposer, ChatThread): ships via Reactor (no dedicated porting agent yet — WIP).

So the boundary Scott asked for is now explicit: native XAML/C# (and Reactor for chat) is what ships; the JSX/design files are the upstream design intent that gets ported into it, and the syncSource/helperAgent name how and who. components.jsx and principles.md say the same thing in prose.

GitHub Copilot maintainer-assistant review — this is automated feedback, not a comment written personally by Scott.

Reviewed head: ed110a1c21c6065de3398f84d88fcdda4b2429e5

This should remain draft. The design-system idea is useful, but the current artifacts are not yet safe as authoritative guidance for a native WinUI app.

The main issues from the paired review:

1. Theme/high-contrast contract: design.json contains fixed light-theme hex/rgba values while the shipping app relies on semantic ThemeResource/system brushes. Please either model Light/Dark/HighContrast variants or mark every color as preview-only and map it to the WinUI resource key agents must use. Raw preview hex must not become implementation guidance.
2. Native remains canonical: the repository’s native WinUI behavior is the source of truth. JSX/catalog artifacts should be described as derived visual examples, not a parallel upstream authority. Please revise the authority block and principles accordingly, and name an owner/sync process for keeping examples aligned.
3. Component parity: the catalog composer omits shipping controls/state such as channel/session routing, speaker mute, send/stop behavior, pending attachments/queue state, and additional action slots. The assistant footer also omits Read Aloud and its state. Either represent the complete shipping contract or label these examples explicitly partial with links to the canonical native owners.
4. Proof/validation: add current-head gallery proof for every exported component, including Light, Dark, and High Contrast behavior where applicable. Add a schema/parse/render smoke check for .agents/design/* so future drift is caught automatically.

Recommended framing: keep native XAML/C# behavior canonical; use this catalog to explain visual intent and reusable patterns, with semantic resource mappings and explicit coverage limits. That would preserve the value of the design artifacts without teaching future agents to hard-code colors or omit native functionality.